From b7bca7b892104e5efb352c165412a7ddd19ebdcf Mon Sep 17 00:00:00 2001
From: Ewan Mellor <ewan@xensource.com>
Date: Wed, 6 Dec 2006 15:20:03 +0000
Subject: [PATCH] Improved task handling model.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
---
 docs/xen-api/xenapi-datamodel.tex | 307 ++++++++++++++++++++++++++----
 1 file changed, 274 insertions(+), 33 deletions(-)

diff --git a/docs/xen-api/xenapi-datamodel.tex b/docs/xen-api/xenapi-datamodel.tex
index 71ffb8b524..cfd264bf94 100644
--- a/docs/xen-api/xenapi-datamodel.tex
+++ b/docs/xen-api/xenapi-datamodel.tex
@@ -109,6 +109,7 @@ The following enumeration types are used:
 \hline
 \end{longtable}
 
+\vspace{1cm}
 \begin{longtable}{|ll|}
 \hline
 {\tt enum vdi\_type} & \\
@@ -133,6 +134,17 @@ The following enumeration types are used:
 \hline
 \end{longtable}
 
+\vspace{1cm}
+\begin{longtable}{|ll|}
+\hline
+{\tt enum task\_status\_type} & \\
+\hline
+\hspace{0.5cm}{\tt pending} & task is in progress \\
+\hspace{0.5cm}{\tt success} & task was completed successfully \\
+\hspace{0.5cm}{\tt failure} & task has failed \\
+\hline
+\end{longtable}
+
 \vspace{1cm}
 \begin{longtable}{|ll|}
 \hline
@@ -273,6 +285,7 @@ The following enumeration types are used:
 \hline
 Quals & Field & Type & Description \\
 \hline
+$\mathit{RO}_\mathit{run}$ &  {\tt uuid} & string & unique identifier/object reference \\
 $\mathit{RO}_\mathit{ins}$ &  {\tt this\_host} & host ref & Currently connected host \\
 $\mathit{RO}_\mathit{ins}$ &  {\tt this\_user} & user ref & Currently connected user \\
 \hline
@@ -330,6 +343,38 @@ void
 
 
 
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_uuid}
+
+{\bf Overview:} 
+Get the uuid field of the given session.
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} string get_uuid (session_id s, session ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt session ref } & self & reference to the object \\ \hline 
+
+\end{tabular}
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+string
+}
+
+
+value of the field
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
@@ -540,16 +585,44 @@ Quals & Field & Type & Description \\
 $\mathit{RO}_\mathit{run}$ &  {\tt uuid} & string & unique identifier/object reference \\
 $\mathit{RW}$ &  {\tt name/label} & string & a human-readable name \\
 $\mathit{RW}$ &  {\tt name/description} & string & a notes field containg human-readable description \\
+$\mathit{RO}_\mathit{run}$ &  {\tt status} & task\_status\_type & current status of the task \\
+$\mathit{RO}_\mathit{run}$ &  {\tt progress} & int & if the task is still pending, this field contains the estimated percentage complete (0-100). If task has completed (successfully or unsuccessfully) this should be 100. \\
+$\mathit{RO}_\mathit{run}$ &  {\tt eta} & datetime & if the task is still pending, this field contains the estimated completion time. If the task has finished (successfully or not) it contains the time the task finished. \\
+$\mathit{RO}_\mathit{run}$ &  {\tt type} & string & if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise. \\
+$\mathit{RO}_\mathit{run}$ &  {\tt result} & string & if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise. \\
+$\mathit{RO}_\mathit{run}$ &  {\tt error\_code} & int & if the task has failed, this field contains the error code. Undefined otherwise. \\
+$\mathit{RO}_\mathit{run}$ &  {\tt error\_info} & string Set & if the task has failed, this field contains the set of associated error strings. Undefined otherwise. \\
 \hline
 \end{longtable}
 \subsection{Additional RPCs associated with class: task}
-\subsubsection{RPC name:~get\_status}
+\subsubsection{RPC name:~get\_all}
+
+{\bf Overview:} 
+Return a list of all the tasks known to the system
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} ((task ref) Set) get_all (session_id s)\end{verbatim}
+
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+(task ref) Set
+}
+
+
+references to all objects
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_uuid}
 
 {\bf Overview:} 
-Poll a running asynchronous RPC invocation and query its status
+Get the uuid field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} (uuid ref) get_status (session_id s, task ref task)\end{verbatim}
+\begin{verbatim} string get_uuid (session_id s, task ref self)\end{verbatim}
 
 
 \noindent{\bf Arguments:}
@@ -559,7 +632,7 @@ Poll a running asynchronous RPC invocation and query its status
 \begin{tabular}{|c|c|p{7cm}|}
  \hline
 {\bf type} & {\bf name} & {\bf description} \\ \hline
-{\tt task ref } & task & The ID of the RPC call to poll \\ \hline 
+{\tt task ref } & self & reference to the object \\ \hline 
 
 \end{tabular}
 
@@ -567,45 +640,53 @@ Poll a running asynchronous RPC invocation and query its status
 
  \noindent {\bf Return Type:} 
 {\tt 
-uuid ref
+string
 }
 
 
-String describing status of specified asynchronous RPC invocation, including estimated completion time
+value of the field
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-\subsubsection{RPC name:~get\_all\_tasks}
+\subsubsection{RPC name:~get\_name\_label}
 
 {\bf Overview:} 
-List all asynchronous RPC calls currently executing
+Get the name/label field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} ((task ref) Set) get_all_tasks (session_id s)\end{verbatim}
+\begin{verbatim} string get_name_label (session_id s, task ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt task ref } & self & reference to the object \\ \hline 
 
+\end{tabular}
 
 \vspace{0.3cm}
 
  \noindent {\bf Return Type:} 
 {\tt 
-(task ref) Set
+string
 }
 
 
-A list of tasks currently executing. Note that
-tasks are associated with users rather than sessions. Thus, if you logout and
-login again with a different session but the same user, this function will still
-return the user's running tasks.
+value of the field
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-\subsubsection{RPC name:~get\_uuid}
+\subsubsection{RPC name:~set\_name\_label}
 
 {\bf Overview:} 
-Get the uuid field of the given task.
+Set the name/label field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} string get_uuid (session_id s, task ref self)\end{verbatim}
+\begin{verbatim} void set_name_label (session_id s, task ref self, string value)\end{verbatim}
 
 
 \noindent{\bf Arguments:}
@@ -617,27 +698,29 @@ Get the uuid field of the given task.
 {\bf type} & {\bf name} & {\bf description} \\ \hline
 {\tt task ref } & self & reference to the object \\ \hline 
 
+{\tt string } & value & New value to set \\ \hline 
+
 \end{tabular}
 
 \vspace{0.3cm}
 
  \noindent {\bf Return Type:} 
 {\tt 
-string
+void
 }
 
 
-value of the field
+
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-\subsubsection{RPC name:~get\_name\_label}
+\subsubsection{RPC name:~get\_name\_description}
 
 {\bf Overview:} 
-Get the name/label field of the given task.
+Get the name/description field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} string get_name_label (session_id s, task ref self)\end{verbatim}
+\begin{verbatim} string get_name_description (session_id s, task ref self)\end{verbatim}
 
 
 \noindent{\bf Arguments:}
@@ -663,13 +746,13 @@ value of the field
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-\subsubsection{RPC name:~set\_name\_label}
+\subsubsection{RPC name:~set\_name\_description}
 
 {\bf Overview:} 
-Set the name/label field of the given task.
+Set the name/description field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} void set_name_label (session_id s, task ref self, string value)\end{verbatim}
+\begin{verbatim} void set_name_description (session_id s, task ref self, string value)\end{verbatim}
 
 
 \noindent{\bf Arguments:}
@@ -697,13 +780,109 @@ void
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-\subsubsection{RPC name:~get\_name\_description}
+\subsubsection{RPC name:~get\_status}
 
 {\bf Overview:} 
-Get the name/description field of the given task.
+Get the status field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} string get_name_description (session_id s, task ref self)\end{verbatim}
+\begin{verbatim} (task_status_type) get_status (session_id s, task ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt task ref } & self & reference to the object \\ \hline 
+
+\end{tabular}
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+task\_status\_type
+}
+
+
+value of the field
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_progress}
+
+{\bf Overview:} 
+Get the progress field of the given task.
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} int get_progress (session_id s, task ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt task ref } & self & reference to the object \\ \hline 
+
+\end{tabular}
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+int
+}
+
+
+value of the field
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_eta}
+
+{\bf Overview:} 
+Get the eta field of the given task.
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} datetime get_eta (session_id s, task ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt task ref } & self & reference to the object \\ \hline 
+
+\end{tabular}
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+datetime
+}
+
+
+value of the field
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_type}
+
+{\bf Overview:} 
+Get the type field of the given task.
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} string get_type (session_id s, task ref self)\end{verbatim}
 
 
 \noindent{\bf Arguments:}
@@ -729,13 +908,13 @@ value of the field
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-\subsubsection{RPC name:~set\_name\_description}
+\subsubsection{RPC name:~get\_result}
 
 {\bf Overview:} 
-Set the name/description field of the given task.
+Get the result field of the given task.
 
  \noindent {\bf Signature:} 
-\begin{verbatim} void set_name_description (session_id s, task ref self, string value)\end{verbatim}
+\begin{verbatim} string get_result (session_id s, task ref self)\end{verbatim}
 
 
 \noindent{\bf Arguments:}
@@ -747,7 +926,37 @@ Set the name/description field of the given task.
 {\bf type} & {\bf name} & {\bf description} \\ \hline
 {\tt task ref } & self & reference to the object \\ \hline 
 
-{\tt string } & value & New value to set \\ \hline 
+\end{tabular}
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+string
+}
+
+
+value of the field
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_error\_code}
+
+{\bf Overview:} 
+Get the error\_code field of the given task.
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} int get_error_code (session_id s, task ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt task ref } & self & reference to the object \\ \hline 
 
 \end{tabular}
 
@@ -755,11 +964,43 @@ Set the name/description field of the given task.
 
  \noindent {\bf Return Type:} 
 {\tt 
-void
+int
 }
 
 
+value of the field
+\vspace{0.3cm}
+\vspace{0.3cm}
+\vspace{0.3cm}
+\subsubsection{RPC name:~get\_error\_info}
+
+{\bf Overview:} 
+Get the error\_info field of the given task.
+
+ \noindent {\bf Signature:} 
+\begin{verbatim} (string Set) get_error_info (session_id s, task ref self)\end{verbatim}
+
+
+\noindent{\bf Arguments:}
+
+ 
+\vspace{0.3cm}
+\begin{tabular}{|c|c|p{7cm}|}
+ \hline
+{\bf type} & {\bf name} & {\bf description} \\ \hline
+{\tt task ref } & self & reference to the object \\ \hline 
+
+\end{tabular}
+
+\vspace{0.3cm}
+
+ \noindent {\bf Return Type:} 
+{\tt 
+string Set
+}
+
 
+value of the field
 \vspace{0.3cm}
 \vspace{0.3cm}
 \vspace{0.3cm}
-- 
2.30.2